The NLB Framework requires a certain amount of information about each item within the Building Information Models (BIM) to be able to understand and represent it appropriately. However. this is very likely just a small subset of the information that end users might need to store for each item.

Serving as the basis for all elements and components in the model, the BIM.Entity class provides a BIM.Entity#attributes property that is basically a standard JavaScript Map. This allows for flexible storage of pretty well any type of data within any entity in the model.

In order for entities to to be easily copied and pasted as text, and for compatible with the core JSON model file format, the keys for each attribute need to be either a string or something that can be easily converted to a string. This means that the attribute property could just as easily have been an object-based dictionary rather than a Map.

However, the BIM data that is common to similar entities and accessed most by the framework is already stored on the entity as object properties. Attributes are additional data created and accessed at user-level, so the data requirements of each model and the types of data stored in each entity are not easily predictable and will very likely be extremely diverse between both different entities and models. As models may contain several hundred thousand separate entities, with every single one of them able to have a potentially unique attribute profile, using a Map frees the JS engine from having to maintain and manage potentially many thousands of different object shapes.

So far this approach seems to be working fine. However, there may be a reason sometime in the future to change things, so it is a highly recommended practice that you use the attribute management methods provided by BIM.Entity rather than accessing the attribute property directly.

Attribute Management Methods

The base entity class provides the BIM.Entity#getAttribute, BIM.Entity#setAttribute and BIM.Entity#deleteAttribute methods for accessing and managing attributes. As described above, you should use these methods to manage attributes on entities rather than directly accessing the underlying Map.

Maps in JSON

Unfortunately, JSON.stringify() and JSON.parse() do not yet support Maps (at least as of Oct. 2024). As a result, the framework does its own conversion to and from Maps when generating model data in JSON-compatible form using the PD.Utils.copyMap and PD.Utils.convertMapToJSON methods.

If you inspect these methods in the code, you will see that they are both able to detect and convert THREE.Vector2, THREE.Vector3, THREE.Vector4, THREE.Matrix3, THREE.Matrix4, THREE.Quaternion and THREE.Color objects to and from arrays. Also, if you attempt to store a BIM entity as a value, only its UUID property will be stored, so your application or custom classes will need to search for it using the PD.GlobalActions.findByUUID method when reading the attribute value.